home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacApp Release 10 / MacApp Release 10 - HD Ready / Libraries / Framework / Includes / UAppleEvents.h < prev    next >
Encoding:
Text File  |  1996-04-03  |  15.0 KB  |  484 lines  |  [TEXT/MPS ]
  1. // UAppleEvents.h
  2. // Copyright © 1984-96 by Apple Computer, Inc. All rights reserved.
  3.  
  4. #ifndef __UAPPLEEVENTS__
  5. #define __UAPPLEEVENTS__
  6.  
  7. // MacApp
  8.  
  9. #ifndef __GEOMETRY__
  10. #include "Geometry.h"
  11. #endif
  12.  
  13. #ifndef __TOOLBOX__
  14. #include "Toolbox.h"
  15. #endif
  16.  
  17. #ifndef __UFAILURE__
  18. #include "UFailure.h"
  19. #endif
  20.  
  21. #ifndef __UOBJECT__
  22. #include "UObject.h"
  23. #endif
  24.  
  25. // Toolbox
  26.  
  27. #ifndef __APPLEEVENTS__
  28. #include <AppleEvents.h>
  29. #endif
  30.  
  31. #ifndef __EDITIONS__
  32. #include <Editions.h>
  33. #endif
  34.  
  35. //----------------------------------------------------------------------------------------
  36. // Mask constants for testing sending mode.
  37. //----------------------------------------------------------------------------------------
  38.  
  39. const long kAEReplyModeMask = 0x0000000F;        // Mask for reply mode
  40. const long kAEInteractModeMask = 0x00000030;    // Mask for interact mode
  41.  
  42. //----------------------------------------------------------------------------------------
  43. // Forward and external class declarations. 
  44. //----------------------------------------------------------------------------------------
  45.  
  46. class TDynamicArray;
  47. class TFile;
  48. class MScriptableObject;
  49. class CAEDesc;
  50.  
  51. //----------------------------------------------------------------------------------------
  52. // CAEDesc : Wraps around a AEDesc and provides lots of extra services. Use this 
  53. // instead of an AEDesc and you'll have access to those services.
  54. //----------------------------------------------------------------------------------------
  55.  
  56. class CAEDesc
  57. {
  58. public:
  59.     CAEDesc();
  60.     CAEDesc(const AEDesc& theDesc);
  61.     CAEDesc(const AEDesc* theDesc);
  62.     CAEDesc(DescType theType,
  63.             Handle theHandle);
  64.  
  65.     // Wrappers for toolbox functions
  66.     
  67.     Boolean CanCoerceDesc(DescType toType) const;
  68.     void CoerceDesc(DescType toType, AEDesc *result) const;
  69.     void CreateDesc(DescType typeCode, const void *dataPtr, Size dataSize);
  70.     OSErr DisposeDesc();
  71.     OSErr GetKeyPtr(AEKeyword theAEKeyword, DescType desiredType, DescType *typeCode,
  72.                     void *dataPtr, Size maximumSize, Size *actualSize) const;
  73.     void PutKeyPtr(AEKeyword theAEKeyword, DescType typeCode,
  74.                    const void *dataPtr, Size dataSize);
  75.  
  76.     // Conversion operator methods
  77.  
  78.     inline operator AEDesc()                { return fAEDesc; }
  79.     inline operator const AEDesc() const    { return fAEDesc; }
  80.  
  81.     inline operator AEDesc&()                { return fAEDesc; }
  82.     inline operator const AEDesc&() const    { return fAEDesc; }
  83.  
  84.     inline operator AEDesc*()                { return &fAEDesc; }
  85.     inline operator const AEDesc*() const    { return &fAEDesc; }
  86.  
  87.     CAEDesc& operator=(const CAEDesc& theDesc);
  88.  
  89.     // Desc content comparison method
  90.  
  91.     Boolean EqualDesc(const CAEDesc& theDesc) const; 
  92.  
  93.     Boolean CompareDesc(const CAEDesc& theDesc, DescType compareHow) const; 
  94.  
  95.     // Methods to get and set data on the fAEDesc.
  96.  
  97.     void SetDesc(DescType theType,
  98.                  Handle theHandle);
  99.     inline DescType GetDescriptorType() const    { return fAEDesc.descriptorType; }
  100.  
  101.     inline Handle GetDataHandle() const    { return fAEDesc.dataHandle; }
  102.  
  103.     long GetDataSize() const;
  104.     
  105.     // The following methods treat the CAEDesc as a list of descriptors
  106.     
  107.     void CreateList();
  108.         // Creates an AEList with no factoring information
  109.         
  110.     long CountListItems();
  111.         // Returns the number of items in the list
  112.  
  113.     void GetNthItem(long index, DescType desiredType, CAEDesc& theDesc);
  114.         // Gets the Nth AEDesc from the list
  115.  
  116.     void PutListItem(long index, CAEDesc& theDesc);
  117.         // Puts theDesc into the list at the index position.
  118.  
  119.     OSErr DeleteListItem(long index);
  120.         // Puts theDesc at the index position from the list.
  121.  
  122.     // The following methods are for storing and retrieving various data
  123.     // types from CAEDescs
  124.     
  125.     void GetFSSpec(FSSpec& fileSpec) const;
  126.     void PutFSSpec(const FSSpec& fileSpec);
  127.  
  128.     void GetRect(CRect& theRect) const;
  129.     void PutRect(const CRect& theRect);
  130.  
  131.     DescType GetType() const;
  132.     void PutType(DescType theType);
  133.  
  134.     void PutString(const CStr255& theString);
  135.     void GetString(CStr255& theString,
  136.                    long maximumSize = 255) const;
  137.  
  138.     void PutBoolean(Boolean theBoolean);
  139.     Boolean GetBoolean() const;
  140.  
  141.     void PutEnum(DescType theEnum);
  142.     DescType GetEnum() const;
  143.  
  144.     void PutLong(long theLong);
  145.     long GetLong() const;
  146.  
  147.     void PutDateTime(unsigned long theDateTime);
  148.     unsigned long GetDateTime() const;
  149.  
  150.     void GetRGBColor(CRGBColor& theColor) const;
  151.     void PutRGBColor(const CRGBColor& theColor);
  152.  
  153.     MScriptableObject* GetObject() const;
  154.     void PutObject(MScriptableObject* theObject);
  155.  
  156.     // Methods for dealing with records
  157.  
  158.     void CreateRecord();
  159.  
  160.     // The following GetKeyXXX and PutKeyXXX methods are for easy access to AERecords
  161.     // The GetKeyXXX methods will not fail but will return FALSE if the key did not exist.
  162.     // This is so you can use them to attempt to retrieve optional keys in a record without
  163.     // handling failure or checking first to see if they exist.
  164.  
  165.     Boolean GetKeyLong(DescType theKey,
  166.                        long& theNum) const;
  167.     void PutKeyLong(DescType theKey,
  168.                     long theNum);
  169.  
  170.     Boolean GetKeyRect(DescType theKey,
  171.                        CRect& theRect) const;
  172.     void PutKeyRect(DescType theKey,
  173.                     const CRect& theRect);
  174.  
  175.     Boolean GetKeyString(DescType theKey,
  176.                          CStr255& theStr,
  177.                          long maximumSize = 255) const;
  178.     void PutKeyString(DescType theKey,
  179.                       const CStr255& theStr);
  180.  
  181.     Boolean GetKeyDateTime(DescType theKey,
  182.                            unsigned long& theDate) const;
  183.     void PutKeyDateTime(DescType theKey,
  184.                         unsigned long theDate);
  185.  
  186.     Boolean GetKeyBoolean(DescType theKey,
  187.                           Boolean& theBoolean) const;
  188.     void PutKeyBoolean(DescType theKey,
  189.                        Boolean theBoolean);
  190.  
  191.     Boolean GetKeyColor(DescType theKey,
  192.                         CRGBColor& theColor) const;
  193.     void PutKeyColor(DescType theKey,
  194.                      const CRGBColor& theColor);
  195.  
  196.     Boolean GetKeyEnum(DescType theKey,
  197.                        DescType& theEnum) const;
  198.     void PutKeyEnum(DescType theKey,
  199.                     DescType theEnum);
  200.                     
  201.     Boolean GetKeyDesc(DescType theKey,
  202.                         DescType desiredType,
  203.                            CAEDesc& theAEDesc) const;
  204.                         
  205.     void PutKeyDesc(DescType theKey,
  206.                     CAEDesc& theAEDesc);
  207.  
  208.     OSErr DeleteKeyDesc(DescType theKey);
  209.  
  210.     // Stream I/O methods
  211.  
  212.     void ReadFrom(TStream* aStream);
  213.     void WriteTo(TStream* aStream);
  214.     
  215.     // Resource I/O methods
  216.     
  217.     void ReadFrom(TFile* aFile, ResType resourceType, short resourceID);
  218.     void WriteTo(TFile* aFile, short resourceID, CStr255& resourceName);
  219.  
  220.     //----------------------------------------------------------------------------------------
  221.     // data members
  222.     //----------------------------------------------------------------------------------------
  223. public:
  224.     AEDesc fAEDesc;                                // the AEDesc record
  225.  
  226.     //----------------------------------------------------------------------------------------
  227.     // static data members
  228.     //----------------------------------------------------------------------------------------
  229. public:
  230.     static CAEDesc fgNullDesc; 
  231. };
  232.  
  233. //----------------------------------------------------------------------------------------
  234. // CTempDesc
  235. //----------------------------------------------------------------------------------------
  236.  
  237. class CTempDesc : public CAEDesc
  238. {
  239.     // This varient of CAEDesc is designed for the occasions when you need to create
  240.     // a descriptor that you will only use within a limited scope. CTempDesc destructor
  241.     // will call AEDisposeDesc for you to simplify cleanup.
  242.  
  243. public:
  244.     CTempDesc();
  245.     CTempDesc(const AEDesc& theDesc);
  246.     CTempDesc(DescType theType,
  247.               Handle theHandle);
  248.     // Initializes the fAEDesc and installs the failure handler.
  249.     ~CTempDesc();
  250.     // Calls Success for the failure handler.
  251.     
  252.     void Cleanup();
  253.  
  254.     //----------------------------------------------------------------------------------------
  255.     // static member functions
  256.     //----------------------------------------------------------------------------------------
  257. public:
  258.     static void CallCleanup(void* context);
  259.  
  260.     //----------------------------------------------------------------------------------------
  261.     // data members
  262.     //----------------------------------------------------------------------------------------
  263. private:
  264.     FailInfo fFailInfo;                            // the failure record that references
  265.  
  266. };
  267.  
  268. //----------------------------------------------------------------------------------------
  269. // TAppleEvent
  270. //----------------------------------------------------------------------------------------
  271.  
  272. class TAppleEvent : public TObject
  273. {
  274.     MA_DECLARE_CLASS;
  275.     
  276. public:
  277.     TAppleEvent();
  278.         // Constructor
  279.         
  280.     void IAppleEvent(const AEEventClass itsEventClass,
  281.                                     const AEEventID itsEventID,
  282.                                     const AEAddressDesc& itsAddress,
  283.                                     long itsSendingMode);
  284.  
  285.  
  286.         // Creates a new AppleEvent message and stores it in fMessage. Supplies
  287.         // defaults for return ID, transaction ID, and sending priority.
  288.  
  289.     virtual void InitializeFromMessage(const AppleEvent& theMessage,
  290.                                        Boolean freeMessage);
  291.         // Stores theMessage in fMessage. This may be a message or a reply.  If freeMessage is true
  292.         // Free the message when freeing the object
  293.  
  294.     virtual ~TAppleEvent();
  295.     
  296.     virtual OSErr SendEvent();
  297.         // Send the apple event. Will not throw an exception. Preferred method.
  298.     
  299.     virtual OSErr SendEvent(TAppleEvent*& replyEvent);
  300.         // Send the apple event and get a reply event. Will not throw an exception. Preferred Method.
  301.  
  302.     virtual TAppleEvent* Send();
  303.         // Send the apple event and return a reply. WILL throw an exception if an error occurs.
  304.         // Present for compatibility - use SendEvent when possible.
  305.         
  306.     virtual void GetAddress(AEAddressDesc& theAddress);
  307.         // Return the target address of the message
  308.  
  309.     void GetProcessSerialNumber(ProcessSerialNumber& thePSN);
  310.         // Return the Process Serial Number for the sender of the message
  311.  
  312.     inline short GetPriority()
  313.     { return fPriority; }
  314.         // Return the sending priority of the message
  315.  
  316.     virtual long GetReturnID();
  317.         // Return the ID assigned to the message
  318.     
  319.     inline long GetSendingMode()
  320.     { return fSendingMode; }
  321.         // Return the sending mode of the event
  322.  
  323.     inline long GetTimeoutVal()
  324.     { return fTimeoutVal; }
  325.         // Return the timeout value (in ticks) used when sending the message
  326.  
  327.     virtual long GetTransactionID();
  328.         // Return the ID of the transaction the message belongs to
  329.  
  330.     virtual void SetAddress(const AEAddressDesc& theAddress);
  331.         // Assign the target address of the message
  332.  
  333.     virtual void SetPriority(short thePriority);
  334.         // Assign the priority with which the message will be sent
  335.  
  336.     virtual void SetReturnID(long returnID);
  337.         // Assign a new return ID to the message
  338.         
  339.     virtual void SetSendingMode(long sendingMode);
  340.         // Specify a new way of sending the message
  341.  
  342.     virtual void SetTimeoutVal(long theTimeoutVal);
  343.         // Assign the time (in ticks) to wait for reply if sending kAEWaitReply
  344.  
  345.     virtual void SetTransactionID(long transactionID);
  346.         // Assign a transaction ID to the message
  347.     
  348.     AEEventClass ReadEventClass();
  349.         // Return the event class of the apple event
  350.         
  351.     AEEventID ReadEventID();
  352.         // Return the event ID
  353.  
  354.     // READING - The following methods retrieve theData from fMessage based on the keyword
  355.     virtual short ReadShort(const AEKeyword theKey);
  356.                                     
  357.     virtual long ReadLong(const AEKeyword theKey);
  358.                                  
  359.     virtual void ReadString(const AEKeyword theKey,
  360.                                  CStr255& theData);
  361.                                  
  362.     virtual SectionHandle ReadSectionHandle(const AEKeyword theKey);
  363.  
  364.     virtual void ReadPtrList(const AEKeyword theKey,
  365.                                     const DescType theType,
  366.                                     TDynamicArray* theData);
  367.  
  368.     virtual void ReadHandleList(const AEKeyword theKey,
  369.                                        const DescType theType,
  370.                                        TDynamicArray* theData);
  371.  
  372.     virtual DescType ReadType(const AEKeyword theKey);
  373.  
  374.     virtual DescType ReadEnum(const AEKeyword theKey);
  375.  
  376.     virtual Boolean ReadBoolean(const AEKeyword theKey);
  377.  
  378.     virtual void ReadRect(const AEKeyword theKey,
  379.                           CRect& theRect);
  380.                           
  381.     virtual void ReadError(long& errorNumber, CStr255& errorString);
  382.  
  383.     // Allow raw read access to a parameter of the message
  384.  
  385.     virtual OSErr ReadParameter(const AEKeyword theKey,
  386.                                const DescType desiredType,
  387.                                CAEDesc& theData);
  388.  
  389.  
  390.     virtual void ReadParameterPtr(const AEKeyword theKey,
  391.                                          const DescType desiredType,
  392.                                          DescType& actualType,
  393.                                          Ptr theData,
  394.                                          long maximumSize,
  395.                                          long& actualSize);
  396.  
  397.     // WRITING - The following methods store theData in fMessage with theKey
  398.     virtual void WriteShort(const AEKeyword theKey,
  399.                                      short theData);
  400.                                      
  401.     virtual void WriteLong(const AEKeyword theKey,
  402.                                   long theData);
  403.                                   
  404.     virtual void WriteString(const AEKeyword theKey,
  405.                                      const CStr255& theData);
  406.                                  
  407.     virtual void WriteSectionHandle(const AEKeyword theKey,
  408.                                            SectionHandle theData);
  409.                                            
  410.     virtual void WritePtrList(const AEKeyword theKey,
  411.                                      const DescType theType,
  412.                                      TDynamicArray* theData);
  413.  
  414.     virtual void WriteHandleList(const AEKeyword theKey,
  415.                                         const DescType theType,
  416.                                         TDynamicArray* theData);
  417.  
  418.     virtual void WriteEnum(const AEKeyword theKey,
  419.                            DescType theEnum);
  420.  
  421.     virtual void WriteType(const AEKeyword theKey,
  422.                            DescType theType);
  423.  
  424.     virtual void WriteBoolean(const AEKeyword theKey,
  425.                               Boolean theBoolean);
  426.  
  427.     virtual void WriteRect(const AEKeyword theKey,
  428.                            const CRect& theRect);
  429.  
  430.     // Allow raw access to a parameter of the message
  431.  
  432.     virtual void WriteParameter(const AEKeyword theKey,
  433.                                 const CAEDesc& theData);
  434.  
  435.     virtual void WriteParameterPtr(const AEKeyword theKey,
  436.                                           const DescType typeCode,
  437.                                           Ptr theData,
  438.                                           long dataSize);
  439.  
  440.     virtual void DeleteParameter(const AEKeyword theKey);
  441.         // Delete the specified parameter from the message
  442.  
  443.     virtual void CheckRequiredParameters();
  444.  
  445.     virtual Boolean HasParameter(const AEKeyword theKey);
  446.  
  447.     virtual DescType ParameterType(const AEKeyword theKey);
  448.  
  449.     virtual Boolean WriteReplySpecifier(MScriptableObject* theReplyObject);
  450.     // Use this whenever you need to return the object's specifier as the result of an event.
  451.     // Makes an object specifier for an object and puts it in the keyAEResult parameter of this event.
  452.     
  453.     void WriteError(long errNum, short errorStringResource, short errorStringIndex);
  454.     void WriteOSError(OSErr error);
  455.         // Report an error back to the client using the errReasonID 'errs' resource.
  456.  
  457.     //----------------------------------------------------------------------------------------
  458.     // static functions
  459.     //----------------------------------------------------------------------------------------
  460. public:
  461.     static TAppleEvent* MakeCreateElementEvent(AEAddressDesc& targetAddress, AESendMode    sendMode, 
  462.             CAEDesc& targetSpecifier, DescType newElementType, DescType    newElementPosition, 
  463.             CAEDesc& initialData, CAEDesc& initialProperties);
  464.  
  465.     //----------------------------------------------------------------------------------------
  466.     // data members
  467.     //----------------------------------------------------------------------------------------
  468. public:
  469.     AppleEvent fMessage;                        // Created by IAppleEvent, Set from InitializeFromMessage
  470.     long    fSendingMode;                        // kAENoReply, kAEQueueReply, or kAEWaitReply
  471.     long    fTimeoutVal;                        // How long should we wait for a response?
  472.     short    fPriority;                            // kAENormalPriority or kAEHighPriority
  473.     Boolean    fFreeMessage;                        // If true then free the message when freeing the object
  474.     
  475.     //----------------------------------------------------------------------------------------
  476.     // static data members
  477.     //----------------------------------------------------------------------------------------
  478. public:
  479.     static AEIdleUPP     fgIdleProc;
  480.     static AEFilterUPP    fgFilterProc;        
  481. };
  482.     
  483. #endif
  484.